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INTRODUCTION 
The UniLsb opens an interactive window into ryour development system, 
Developers of micraprocessor-based devices, selva are alrearly acc 


ae 


custoamed ta 
traditional debugging, can just as easily monitor their aysteras’ real-time 
performance, You can execute and fully test your programs before embeddin 
thera in ROM, even before the target hardware is complete, 


The powerfial UniLeb concept offers transparent emilstion, non-intrusive 
analysis, and precise specification of execution cycles. All target activity can he 
monitored, including kus signals, port 1/0, register contents, target RAM, ancl 
emulation ROM. Prototyping, debugging, and optimizing are all done from your 
IBM-compatible computer, | 


Take the time to explore all of the UniLeh functions, The an alyzer, trig 
debug, assembly, and memory facilities work together seamlessly to greathy 
increase your productivity, 

[figure 1-1] 


What The Tutorial Covers 

This tutorial introduces the major UniLah icomponents, providing a basic 
understanding of the software and specific 290 operations, Included is 

sirnple prograrn that runs on the Orion Micro Target, In the course of 
exploring that program's operation, you will exercise the UniLab thor oughly, 
Follow the step-by-step instructions, and it will be eazy to learn all the related 
commands and finctions, You will use the systern productively in avery short 
time. 
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Introduction 


How to Use The Tutorial 

Be sure to sit within easy beeen of your computer when you use the tutorial. 
Follow the instructions for connecting it to the UniLah. Then. ev ery time you 
open the tutorial: 


+ First, turn on the system. 

«Read a section, doing all the exercises, 

+ Experiment with the meterial you learned, 
* ae abresk before proceecing further, 


We suggest a rest after each chapter, to let the material sink in ancl to avoid 
information overload. It is best to proceed sequentially, from beginning to 
ending, but feel free to explore the aystem as your interests dictate, 


What You Need to Proceed 
All of the UniLeh's resources can be tapped immediately, without complex or 
ostly add-ons. Here is all you need: 


+ IBM PC (or compatible) computer with: 
two floppy disk drives (or optional hard disk) 
320K RAM 
one standard serial port 
DOS version 2.0 or higher 
+ The UniLeh unit 
+290 Personality Pak (includes microtarget with emulation module, and 
software}, 
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Introduction 


Get Connected 


setting up the UniLab system is easy. The herchware is reach to plug into anny 
IBM PC-compatible host computer, The software rust he backed up onto your 
system disk, Then you are reachy to hecorne familiar with the powerful new 


tools at your disposal, 


Install the Hardware 

First, unpack the UniLeb. Two cables emerge frorn the back, Attach the one 
with an RS-232 connector to the hast computer's serial port fit uses a 

. Standerd, 25-pin serial port; if the hast port has only 9 pins, you will need ta 
get an aclapter). Plug the other cable into a power outlet, 

[figure 1-da] 

Now open the Personality Pak and look at the raicroterget hosrd, leaving it in 
the protective box. The smaller, elevated hoard holding the Z80 CPU ig called 
the ernulation module. Check to see that it is still firraly seated on the 
microterget after shipping. The clearly Ishelled power jumper wire provides 
power to the board, and would ke disconnected if the ernulation rnodule were 
used on another board with its own power supply, 

[figure 1-4b] 

Handle the board as carefully as any other electronic circuitry: keep it cleen, 
keep liquids sefely away, ancl avoid impacts or pressure on the various 
components, Do not allow anything to cause an electrical short bebween the 
pins or other conductors. 


Two ribbon cables come off the ernulation rnodule. Their free encs are leheled 
“ernulator cable" and "analyzer cable." 


Plug the emulator ceble into the UniLsb front panel connector rnarked "8/15 
Bit In-Circuit Eroulator." A small, Plastic "key" indicates the top side of the 
cable. Taking care not to bend any of the pins, press evenly until the cable is 
seated snugly in the connector. In the same w ¥, plug the analyzer ceble ints 
the "48 Channel Bus State Analyzer," : 

[figure 1-dc] [figure 1-4d] 

Now you have finished installing the UniLsb hardware. Turn on the power 
switch on the front panel of the UniLsh: the indicator light confirms that the 
unit is turned on, 
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Install the Software 
(For installation on a hard disk, please refer to the "Software Installation" 
insert that accompenies the UniLsh diskettes.) 


1. Mske a ayatem diskette, 
Boot the host computer with a copy of the DOS version (3.2 or higher} 
you will use with the working UniLsh system. Insert a blank diskette 
into drive B, Format it as 4 “bootsble” system diskette by using the 
FORMAT BE: /S command, 


2. Copy all UniLsh files to the new cliskette, 
Pat away the original DOS diskette and insert the master UniLeh Main 
Program diskette into drive A, Copy all the UniLsb files onto the new 
diskette in drive B by using the COPY A:*.* B: command. 


3. This is also a good time to 1 make abackup copy of the UniLeh Glossary 
diskette (do not put the glossary files on a system diskette’. 


4, Now put the rnaster UniLeh diskettes safely away, 
5. Put the new, bootable copy of the UniLah Mein Program disk in drive A. 
The copy of the UniLeb Glossary should he in drive B, where it will be used for 


on-line help functions, 


Ifyou encounter any difficulty with these srocedures, please refer to your DOS 
o a wv I v 
roenual, . 
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THE UNILAB ENVIRONMENT 


Master the User Interface 
Start the UniLeh system 

Get help with commands 

Use menus & fimction keys 
Leave the program 


EXPLORE THE UNILAB ENVIRONMENT 


The UniLeb environment provides immediate sccess to the entire 
development system. Analyzer, debug, assembly, and memory fictions are co- 
resident at all times, An easy way to become familiar with the general 
capabilities of the UniLsh is to browse through its menus. You will see the 
various components of the software system and their relationship to both the 
target and UniLeb hardware. Later, detailed investigation will fill in the overall 
picture you gain in this section, 


start the UniLab System 

Turn on the UniLeb power switch, Put your working copy of the UniLah system 
diskette in drive A and the glossary diskette in drive B, then boot the host 
computer, 


At the A> DOS prompt, type ULZ80 to execute the UniLsh softwere. 


Checking for Problems? 

Ifthe last wordon the screen is "Initializing..." andyour keyboard seems fronan, be sure the red 
indicator light on the front ofthe UniLab indicates thatthe power switch isturnedon, Alsacheck | 
that allcsbles ara snugly attached, Then press Ctrl-Breakto freethe keyboard, andtype INIT, 
Coramunication with the UniLlab maybe disrupted by devices connectadts other RS-292 ports. If 
trouble occurs, try connectingthe UniLeb to a different RS-232 port, If it persists, seethe Unilab 
Reference Maxual for "Troubleshooting." 


Enter Commands 

The program starts out in commend mode. The introductory cisplay provides 

generel information ebout on-line help and the menu mode of operation. A 

cursor indicates where cormmands may be entered. 

[figure 2-4h] 

Try typing WORDS followed by a carriage return, 
An alphabetical list of all UniLah commends is displayed with brief usage 
notes, The concluding "PgDn for more" always appears when more data 
can be cispleyed by pressing that key. Try it, or press the Enter 
(carriage return) key to end the listing, When the listing terminates, 
the "ok" prompt end a cursor are displayed, 
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Enter a misspelling: type WIRDS and cerrigge return, 
A “not recognized" messege appears snd the incorrect entry is 
underscored, — 


Get Help On-Line 
The UniLsb softwere will provide detailed assistance when you need it, 


Type HELP BINLOAD followed hy a cerriege return, 
A screenful of information is presented ebout the BINLOAD commend: 
what it does, its usage, and an example, 


Now try a misspelling: HELP WIRDS, for instence. 
The “WIRDS not in glossary" reply indicates that help is not availeble for 
that subject, On-line help is availeble only for commends UniLsh 
recognizes, | 


Enter the single word HELP. 
The resulting text explains how to get assistance with specific 
commends and with comrnand-mode operations assigned to the 
function keys. This is the same introductory screen that appesrs every 
time you start the program with ULZ8O. 
[figure 1-7] 
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select Functions by Menu 

This tutorial relies heavily on the UniLeh menus. With them, there is no need 
to learn a lot of commends before using the system — function keys offer easy 
access to most operations, Later, you will find the commend mode more 


expedient for many operations. 


Press F10 ta enter the menu mode of operation, 
The "UniLeb Main Menu" is displayed on your screen. The menu 
presents a list of choices and the fiction Bey used to select each o 
[figure 2-dal] 
selecting any menu iter, except F10, will display a sub-men 


Press F§ to exarnine the "Toolkit Routines," 
The sub-menu presents a list of choices, 


Press F10 to return to the main menu, 
Press F10 at any sub-rienu to retura to the main i 


Leave the Program 

When you are reacly to stop work, type BYE. Yen will be left at the norrnal DOS 
prompt, When working with the UniLab software, a system reset ar power- 
down is safe at any time. 
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USE THE BUS-STATE ANALYZER 


Observe target execution without interfering 


Analyze Program Execution 
Eneble mernory and load a program 
Disasseroble ernulation ROM 

» Capture and display a trace 

scroll the trace display 

Interpret the display 


Choose Other Analyzer Options 
sample cycles while executing 


Use the Bus-State Analzyer 
Developing microprocessor-based devices goes hand-in-hand with dekugging, 
the most time-consuming phase of mar ¥ projects, Interrupting the target 
processor anc single-stepping through its instructions until a problem is 
detected can be Ishoricus and, for certain problema, very inefficient, UniLsh 
captures information about the real-time execution of your target system, 
allowing you to track down bugs and test hypotheses quickly, 


In this chapter, you will observe a programa running on the microtarget, Bus 
cycles will be recorded in the trace buffer and displayecl to the user; all 
program instructions and their effects will be monitored without disturbing 
target execution, 


280 Tutorial — Page 12 


Vas the Bus-Stete Analyzer 


Load a Sample Program 
Boot the UniLeb system snd enter menu mode by pressing F110. 


Press F2 to use the "Load or Save a Program" sub-menu, 

[figure 3-2a 

select F2 ta load a binary object file fram disk, 
UniLsb requests the memory address where you wish ta start loading 
the file. Enter O to start loading at address 0000, UniLeh naw requests 
an ending address for the program, 


since you clon't know the length of the sample file, just enter FFFF, 
UniLah will stop loading a program at the ending address you specify or 
at the end-of-file, whichever it reaches first, After you enter the ending 
address, the program displays the commends you would type ifycu 
weren't using the menus, and requests the name of the file you wish to 
load, 


Type DEMO3.TSK for the filename, 
UniLsb loads DEMOS3.TSK and shows the program's ending accress, 
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Uae the Bus-Stete Analyzer 


Disassemble Emulation ROM 
since this is your first use of the system, before proceeding further you may 
wish to confirm that the program hes been loaded, 


Press F3 for the "Examine and Change Program Memory” sub-menu. 
This menu provides several options we will explore later, 
[figure 3-3b] 

For now, press F2 to view a disassernbly of the code, 


The program requests a starting address for the disas ssembly, 


Enter 0 as the starting acldress, 
The program now asks for the number of lines you wish to disasserable 
— it will provide five lines by default, if no value is entered, 


Press Enter to see five lines. 
The equivalent keyboard command is displayed, followed by the listing, 
The three columns represent a pubes kus data, and dissssernblecl 
280 mnemonics. These will be ussed shortly — for now, we are just 
confirming that the target es is in rnemeory. 
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Une the Bus-Sterte Analyzer 


Capture and Display a Trace 
Return to the main menu ky pressing F1Q, 


Press F4 to use the analyzer sub-menu, 
[figure 3-2] 
Press F] to display the initial cycles of prograrn execution. 
This displeys the equivalent keyboard command (STARTUP}, then 
issues a reset to the target system, and records initial bus activity, 
[figure 3-4] 
The display shows what took place during the first cycles of the DEMO3,TSK 
program's execution on the target system, All bus activity was recorded until 
the anelyzer's trace buffer was filled, then the buffer’s contents were uploaded 
to the host computer, The microtarget's LEDs reveal that the target aystem 
continues to execute the program even after the ana yer display is complete, 


scroll the Trace Display 
More data is chtained than can he sheavn on one CRT screen — the UniLsh 
trace buffer holds 170 (A4 hex} target cycles, 


Use the Down-Arrow and PgDo keys to look through the trace, 


(The up-erraw snd PgUp keys scroll back through the CRT history, not 
through the trace buffer's contents.) 


4 


Press the Home key to return to the beginning of the trace. 
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Uae the Bus-State Anulyzer 


Interpret the Display 
The colurnns of data displayed by the analyzer are showa below: 


The first line of our sample trace tells us this: The 0 in the cy# column sheavs 
this is the first cycle of the trace — called the “trigger” cycle, We will 
disregard the CONT column in this tutorisl (see chapter 6 of the UniLeh 
Reference Manuel for details}, The ADR column shows that execution during 
this bus cycle was at address 0000. DATA column contents 31FE16 are 
disassernbled to the right: load into the stack pointer the value 1OFE, The 
HDATA and MISC columns display input from the UniLsb's scditional signal 
wires; their values float high when unused (these columns can be eliminated 
from the displey with the rode panel, discussed later), 

[figure 3-5] 

Refer to the next line in the trace display, From the cycle number, we see that 
it took three bus cycles to fetch the previous instruction, 


Note: if DATA contains a two ‘hyte iramediate value, the bytes are shown in 
reverse order (Intel format), 


Choose Other Analyzer Options 

90 far, you have traced the first Ad (hex) bus cycles of the target program's 
execution. Some menu options illustrate other simple uses of the analyzer, You 
can try them now, while you are in the analyzer sub-menu, 


F2 — displays the most recent 170 cycles when you press the key, 
F6 — samples shout two bus cycles per second. Press any key to stop, 


F6 — samples about two address references per second, Press any key to stop, 


The UniLeb can also show what happens to the target system after (or before) 
& particular event takes place. And when analyzing execution, it is often useful 
to record only certain types of bus cycles, The next chanter shows how ta 

observe any part of a target program's activity. You will use more sophisticated 
UniLeb functions to understand DEMO3,TSK's execution on the microtarget. 
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Build Analyzer Triggers 
UniLab allows you to define triggers that recognize target-board bus events of 
any type, and to stert (or end) a trace at that point, This makes it easy to 
ohserve a program's behavior after a particular data value, range of addresses, 
or other user-defined event appears on the bus. You can record all bus cycles, 
or only cycles that match a trigger description, 


The powerful capabilities of triggers deserve close inspection, heginning with 
simple trigger specifications and progressing to more complex examples that 
use filters and qualifiers. Here we will use them to understand more of 
DEMO3.TSK's execution on the microtarget, 


Inspect Current Trigger Status 
With the sample progrem loaded, press Fl at the analyzer sub-menu (the 
STARTUP command), which sets a default trigger and captures a trace, 


Type TSTAT to view the current trigger status, | 
This cormmend displays the current trigger specifications, RESET 
indicates the target system will be reset when the analyzer is started, 
The DCYCLES value is the hex number of bus cycles the analyzer will 
record after it detects en event that matches the triggers specs, 0 
QUALIFIERS indicates that na qualifiers (discussed later) are heing 
usec, 
[figure 4-2a] 
Use Preset Triggers 
When defining analyzer triggers, you swill frequently use one of three 
"normalizing" words to cleer out any previous trigger specifications, They 
differ only in the number of bus cycles they tell the analyzer ta record efter 
the trigger event (the DCYCLES variable), 


Type NORMB followed by TSTAT to see the effect. 
The trigger stetus shows that the analyzer will record only 4 bus cycles 
after the trigger before ‘freezing "the trace buffer's contents, 
[figure 4-2] 

Try typing NORMM end NORMT and check their effects with TSTAT, 


NORMB places the trigger event at the bottom of the trace buffer, preserving a 
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Bulld Analyzer Triggers 


record rostly of pre-trigger cycles, NORMM places the trigger at the middle 
of the buffer, NORMT places it at the top of the buffer, recording the greatest 
number of post-trigger cycles. 

[figure 4-3] 


Define a Simple Trigger © 

The analyzer watches for an event that matches the current trigger 
specifications, and records the number of post-trigger cycles set by the | 
NORMx wards discussed above. To define an analyzer trigger, you just specify 
the characteristics of the desired target event, 


Type NORMT to set the trigger near the top of the trace kuffer, 


Go to the enalyzer menu and press F 1, 
The display shows that during the first eleven cycles, the ZE0 register: 
oO 


are initialized, followed by an LDIR instruction that transfers a block of 
memory from ROM to RAM, 


Use PgDn to scroll the display through the repeated LDIR /read Awrite 
sequence, 
At cycle #94, the target system begins executing new instructions, 
starting at address 0016, But using PgDn again reveals that you have 
reached the end of the trace buffer. A trace that begins when address 
Q016 appears on the bus will better show what happens next, 


Press F3 to define an address as the analyzer's trigger, When UniLab prompts 
you to supply the address, enter 16. | 
The terget system is reset (because RESET is enabled), and the analyzer 
begins looking for a bus cycle containing address 0016, When it 
appears, the trace buffer fills end its contents are displayed, The target 
system continues ta execute, | 
[figure 4-5a] 
You can see by the listing that the program loads a velue into the A 
register and sends it to target port 7B. Next, another value is loaded 
into A, sent to port 79, and the value in Ais rotated. Then the routine at 
address O0A0 is called, There, you can see that 40FF is loecled into the 
HL registers, then Lis decremented in a conditional-jump timing loop. 
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Type TSTAT. 
Your trigger spec (16 ADR) has been added to the trigger statis — as 
long as it appears here; it is part of the current trigger specification. 
[figure 4-5] 
The three-byte instruction st 0016 jumps to 0082. Curiosity might lead 
us to find cut what happens when the program reaches address 0019, 


Use FS to trigger the analyzer when address 19 appears cn the bus, 
The analyzer displays a the Trigger Wait Status message while it waits. 
Address 0019 never appeers, so press any key to interrupt the search. 
[figure 4-fic] 
Use TSTAT again now, 
The 19 ADR trigger spec repleced the previous 15 ADR. When you. 
specify a new value for the same input group, it replaces the eerlier one. 


You can trigger a trace with a value in any of the displayed fields except the 
disassernbled mnernonics and the cy# value (which is relative to the trigger 
event), Here is an example using data input: 


Enter NORMT 80 DATA S to clear the old setting and start the trace when 
80 appears in the clata field. 
The display shows a trace that begins (cycle #-1) with 90, the second 
byte in the data field, being loaded into the A register. 
[figure 4-7] ; 
Any byte in the data field can be used as a trigger. And while you cannot 
define a trigger with mnemonics, it is easy to use the opcode values in 
the data field if you want to trigger on a particular type of instruction. 
For exemple, OF DATA will trigger on an RRCA instruction, 
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Extend Trigger Power 
You can start a trace when any one of several values appear, 


Enter RESET" so the systern will trace the executing system without 
restarting it, . 
Reset can be disabled with RESET" and enshled by typing RESET; or 
use the Mode Panel, discussed later, : 


Type NORMB to clear the Previous trigger specifications, 


Type 80 DATA ALSO 40 DATA S to trigger the analyzer when either of 
those data values appears. 
- This allows either data value to trigger the analyzer. As usual, UniLah 
displays the Trigger Wait Status line if it must wait for the trigger event, 
Press 3 repeatedly, and you will find that the value 40 frequently shows 
up on the data bus, in the timing loop at address OOAQ, Less often, &0 
triggers the trace when the contents of A are written to port 79, 


ALSO adds a value to the current trigger spec, and as meny values cen 
be edcled as you find useful: without it in the above example, 40 DATA 
would have overwritten the preceding G0 DATA, 


There is an additional precaution when using ALSO with address input: The 
acldresses sre composed of twa, eight-bit input values. Cross products will be 
produced if the upper bytes of ALSO-ed addresses do not match, and can 
cause @ trigger on unanticipated values, 
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Trigger on a Range of Values 

Now type NORMT AO TO AQ ADR Sto trigger the analyzer on a range of 

addresses, 
This address range contains the delay loop instructions, The trace 
begins with the first cycle that conteins an address in the range AQ to 
Aa, TO is most often used with address or data input. 


The purpose of these cycles is fairly self-evident, so it will be usefial to 
trigger a trace when eny other aperstion takes place. 


Exclude Values from Trigger Specs 

The previous exemple demonstrated haw TO is used to specify a continuous 
range of values, and how ALSO includes multiple, non-continuous values in a 
trigger spec, 


Many programs, including DEMO3.TSE, repeat one operation frequently 
during execution. You can instruct the analyzer to ignore that operation and 
trigger when any other event takes place, NOT is used to prevent single 
values, or renges of values, from acting as triggers, This becomes valushle for 
trapping ahead address or bad dats. In cur example, it is used to trigger on 
target activity outside the delay loop, 


First, type NORMT S. 


Enter NOT AQ TO AS ADR S. 
The trace begins with the first operation that does not contain an 
address in the range 0040 through OOAS. Here it is reacling the return 
address, which conteins a jump to the Program's main loop. This loop, 
at address 98, sencls the value in 4 to the target port and rotates the 
contents of A before calling the delay loop at address OOAQ once ogain. 


Remember that you can use TSTAT to see how Unilah interprets your trigger 
specifications, 
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Trigger on Multiple Fields 

You have defined triggers using values from a single column of the analyzer 
display at a time, However, it is just 93 simple to incorporate several fielcls into 
your trigger specifications, 


Enter NORMB 79 LADR 80 DATA 3 
DEMO3.TSK, as we saw earlier, sends the value SO to the target port, 
Here, we specify a trigger with 79 in the low address hyte and 80 as the 
data byte, The resulting trace shows the value 80 being output to port 
9, followed by the rotate operation, 
[figure 4-9] 

Enter NORMB 79 LADR NOT 80 DATA S to see what else gets sent to port 

79, 
Cycle#0 contains a different value being output. Press 5 several times, 
and you will see the output values that result from rotating the contents 
of register A. These values determine the changing pattern displeyed hay 
the microtarget's LEDs, 


Any combination of trigger specifications may be used: 

* ALSO performs a logical "or," triggering the analyzer when one value or 
another appears in one of the input fields, | 

+ TO extends that concept to any value in a renge. 

+ NOT triggers on any value cutside the specified number or renge of 
nurnbers, 

+ Logical "and" operations ocour when you define trigger specs for more 
then one of the input groups (6.¢., when the desired trigger event 
contains a specific address and data value}. All of the current Secs 
must be met to trigger the ana yeer, 


Exercise a few, simple combinations of these commands before going on ta 
learn further features. If no trace results after issuing the S command, it i: 
beceuse the trigger event you specified never occurs, 4 trigger's result may 
vary, depending on whether reset is enshled or disebled, Use the NORMx 
words to clear cut your trigger specifications, as neecled., 


"A 
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Filter the Trace 

90 fer, you have learned how to trigger the UniLsh snalyzer's trace fiction. 
That is, you can begin a trace at any time by describing a specific target bus 
event, You can also specify the characteristics of the cycles you wish ta 
examine, and only those will be saved in the trace buffer, With this conditional 
recording of target bus cycles, the display focuses only on the most valuehle 
information, 


The filter commend clears sny previous trigger specifications and will record 
AQ hus cycles that match the filter characteristics. 


Type ONLY 79 TO 90 LADR S to record only cycles with a low address byte 

in the declared range, | 
The Trigger Wait Status line appears while events matching the filter 
spec fill the trace buffer. Then the data is displayed; the "“f" to the left of 
each row inclicates that this was a filtered trace. These cycles represent 
the main program loop, including output to target port 79, 
(figure 4-10] 

Enter ONLY NOT AO TO AQ ADR 5S, 
This trace begins with the first cycle that fells outside the declered 
range of addresses, and all subsequent cycles in that range are filtered 
out of the trace. This trace is similar to the one obtained above, but 
includes read and write cycles generated hy the RET and CALL 
instructions, 


(In the previous section, this sarne specification wes preceded by 
NORMT instead of ONLY, and just defined the trigger event; post- 
trigger cycles were not filtered.) 


Eneble reset of the target system hy typing RESET. 

Type ONLY WRITE § to record only write operations, 
The first 20 lines in this trace are write cycles from the block-move 
operation at address 0014, The rest were generated ky the CALL 
instruction. As the next example shows, you can exclude these initial 


operations from the trace, 


WRITE is a macro that specifies a preset renge of CONT values, READ 
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end FETCH ere macros that work similerly, 


Qualify a Trigger Event 
You cen deley the analyzer's search for a trigger until after a quelifing event 
appears on the target bus, 


Type NORMT WRITE AFTER 191F ADR §S. 
The analyzer waited until address 191F appeared on the bus, then 
_ Sterted looking for the trigger (WRITE), Cycle #0 contains the first 
write cycle after the initial block-move operation. Use TSTAT to see 
how quelifiers, defined with AFTER, are noted in the trigger stabs. 


Type ONLY WRITE AFTER 181F ADR S§. 
The filtered trace contsins only write operations after ecldress 181F 
eppesred, These sre all cycles that store a return eddress for the timing 
loop. 


You could elso trigger the analyzer at the beginning of the output loop after 
that loop has already executed once. In DEMO3.TSK, we know that after the 1 
in Ais first sent to terget port (address 0089), Ais rotated, and the delay loap 
at OOAO is called before returning to 0038 to output the next value, 


Type NORMT 88 ADR AFTER AO ADR §S. 
The analyzer waits for the quelifier address 0040 to appeer on the Ins, 
then triggers the trace with the next occurrence of address 0088, 


[simple quslifiers chart from reference roanual ] 
Up to three qualifiers can be used in a trigger specification. The qualifiers 
must occur in sequential cycles, starting with the lest one entered, then the 
next-to-last one entered, etc. The trigger event can occur at any time after its 
qualifiers appear on the target bus. 
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USE THE DEBUG FEATURES 


Establish Debug Control 

| Set a breakpoint 

Read the breakpoint displey 
single-step the target system 

Resume execution to a new breakpoint 
Follow jumps and loops 


Alter Register Contents 


Trigger a Breakpoint 
Define debug triggers 


Display the Alternate Registers 


Read and Write to Target Ports 


Use the Debug Features 
The UniLeh system provides full-featured debug facilities. You can sat a 
breakpoint, or issue a non-imasksble interrupt from the keyboard, to halt the 
target prograrn and single-step through its execution, You can view and alter 
the contents of registers and memory, and use bus events to trigger 
breakpoints, 


These tools are used while special debug hardware controls the target 
processor. 4 few bytes of emulation ROM (the reserved area and the overlay 
area), and the processor stack are uzerl hy dekugd operations, (See Target 
Application Notes.) 


Establish Debug Control and Set a Breakpoint 

Load DEMO3. TSK, and use the main menu's F6 to get to the debug azb-menn, 
The display shows the functions that are availehle in menu mode, 
[figure 5-2a] 

Press F1 to esteblish debug control, 
Debug control must ke estsblished before other debug options can be 
used, Here, the prograrn requests a breakpoint address, 


Type 88 and a carriage return to set the address, 
The equivalent cormmand line RESET 88 RB esteblishes dehug control 
at address 0088, (RESET enables the target system to be reset by RB.) 
[figure 5-2] : 
The breakpoint display shows the registers and their contents, prior to 
the effects of the current instruction, followed by the address, opcode, 
and clisassembly, 


Here, the contents of DE and HL have chenged since initialization 
becauze of the block-move Operation, IN and TY hold arbitrary values not 
used by DEMO3.TSK, The "A" kyte of AF contains the 01 to be output by 
the current operation. (F is the flag register: its bits are shown to the 
right in parentheses, A capitel letter means the bit is set, lower-case 
means it is reset, and a hyphen means the bit is unused. See the Target 


Application Notes.) = 
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Use the Debug Features 


Single-Step the Target System 


Press F3 to execute the next step of the program. 
The breakpoint display shows unchanged register contents, and the 
RRCA& instruction, 


Press F3 again, | 
Note that the AF value has changed (because of the RRCA), end that the 
_ Current instruction calls the delegy loop at AQ, 


Press F3 once more, . 
The N command issued hy FS "falls through" loops and branches, Naw 
the breakpoint display shows the processor's state after its rebum from 
the delay loop. The current instruction jumps to the rain program 
loop. = 


Follow Jumps and Loops 
To follow the jump, press F4, 
As the address shows, the NMI command followed the program's jump 
instruction, 
[figure 5-4a] 
Type LP to execute the entire loop once, 
The lighted LED advances one Position with each iteration of this loop, 
LP is a quick way to execute a loop once and stop at the same address, 
LP only works when the Program is stopped at an address that will he 
executed again, 
[figure 5-4] 


Alter Register Contents 

DEMO3.TSK rotates a Single bit in register A, using it to animate the 
microterget's LEDs, While at a breakpoint, you can change the register's 
contents to a new bit pattern and see the effect, Here we will put a different 
value into A just before the output /rotate sequence, 


Ifyou followed the instructions above, your breakpoint display should show 
address 0088, with the OUT (79),A instruction that will output the current 
contents of A. We will not want to change the value of the flags register (F) at 
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Uae the Debug Featurey 


this time, so type 7Fxx =AF <Enter>, where xx is the current value of F in 


your breakpoint display, This replaces the current value of Awith 7F, 


Enter the command RZ to resume execution, 


The microtarget resumes execution with the new register contents 
intact, and without resetting or resterting the program, The LEDs now 
exhibit a new pattern, even though you have not modified the program 
itself, 


Now, with the program executing, press F4, 


This sends a non-maskable interrupt to the target processor, It gains 
dekug control of the running system within a few cycles, and genera 
a breakpoint display, When you are already at a breakpoint, NMI sing 
steps through normal program flow. 


tes 
le- 


Resume Execution to a New Breakpoint 
see Execution to a New Breakpoint 


Press F2 to resume execution from the current breakpoint until a new 
breakpoint is reached, 


Respond with AO as the new breakpoint address, 


0 
The equivalent command is AO RB, The breakpoint display is shown 
when that address is reached. | 


RB, unless it is preceded by RESET, allows a program to continue 


execution with a new breakpoint get, 


For other ways to resume execution after esteblishing debug control, use 
function key choices frorn the analyzer and debug menus, or directly enter: 


RZ to resume execution from the current state, 

<adr> G to exit debug control and resume execution from any 
address, 

<adr-a> <adr-b> GB to resume execution at address-a, with a breakpoint set 
for address-h, 

<adr> GW to go to an address and wait for an analyzer command, 

STARTUP to reset and start the microterget and the analyzer, 


NORMx <trig> S to restart the analyzer and reset the terget (if RESET is 
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Une the Debug Features 


enabled), providing a trace of execution when a trigger 
appears, 


Define Debug Triggers 

Earlier, you learned a set of commends to start the onalyzer at any point 
during target execution. The sarne trigger-specification commends can set a 
breakpoint. When so used, triggers issue an NMI to the target processor, 
instead of affecting the trace buffer. (For debugging purposes, triggers set a 
qualifier internally, so AFTER should not be used.) 


Type RI, the debug equivalent of the analyzer's NORMx words. 


Enter 79 LADR 20 DATA SI ta interrupt the processor after 20 is sent ta 
port 79, 
The RI... SI sequence gains debug control within a cycle or two after 
the specified trigger event. Here, A has already been rotated and the 
current instruction calls the delay loop. SI is the debug version of S, 
[figure 5-6] 


Display the Alternate Registers 
The Z80's alternate register set can be included in the breakpoint displey, 


Type SHOW-ALT, 


Now enter RESET 88 RB (or use Fl in the debug meni), 
The display now shows the contents of the alternate registers, 


Type SHOW-ALT' and press F3 to execute the next instruction, 


The display returns to its default state, without the alternate register 
display. 


Puge 29 


Uae the Debug Fenturen 


Read and Write to Target Ports 

The sample prograrn, DEMO3.TSK, controls the microtarget's LEDs hy 
sending values ta port 79. Two commands make it possible ta reacl a port's 
contents, and to send a new value to a port. 


With DEMO3.TSE loaded, use STARTUP to get the program going, 
Type NMI to gain debug control. 


Enter 79 INP <carriage return> to see the hex contents of port 79, 
The resulting number is the value that set the current LED pattern, 


To try different port cutput, type AA 79 OUT, 
The LEDs now light up according to the bit pattern of AA hex, 
Experiment with other values to see their effects. 
[figure 6-6] 


Experiment hy setting some breakpoints and single-stepping through the 
target system's execution. You can gain dekug control at any address that 
contains the first byte of an opcode. Ifuse an invalid address as 4 breakpoint, 
the systern will wait indefinitely — when this happens, press the Enter key to’ 
generate a harclware interrupt, . 
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OPERATE ON MEMORY 


Disassemble From Memory 
net a starting memory address 
Choose length of disassernbly 


Examine and Alter Hex Memory Dump 
select a starting mernory eddress 

Move through the display 

Edit hex or ASCII values 

save the changes 


Operate on Memory 
The UniLsh includes severel tools that work directly on memory, You can 
disassemble the contents of memory to get an assembly code listing, or use a 
hex/ASCII editor to examine end change memory. 


Disassemble a Program 
We will begin locking at memory operations with a simple disassembly of the 
program in ernulation ROM, Load DEMO3.TSK, as described earlier, 


At the msin menu, press F3 to display the sub-menu of memory operations. 


Use F2 to disassemble from memory, 
As the program prompts you for input, enter O as the starting address 
and 7 for the nurmber of (hex) lines you wish to disassemble. 

[figure 6-2] 
The programm displays the equivalent keyhoard command 0 7 DM, 
followed by the disessembly. These are the initialization instructions, 
the block move, snd a jump instruction to the prograrn's main routine 
followed by unused acclresses. 


Now press F2 again, entering @2 for the starting address and 7 for the 
number of lines, 

Here is the DEMO3.TSK code that controls the LEDs. 

- After initializing the port chip's control register (1/0 address 7B), 

- it loacls a value into A at address 0086, 

- sends that value to port "A" of the port chip (1/0 address 79), 

- rotates A’s contents, calls the delay loop at QOAQ, and 

- jumps back to address 0088 to output the new bit pattern from A. 


Any address can be the starting point of a disassembly, and there is no limit to 
the number of lines. You can disassernble emulation memory and, with debug 
control, target RAM, Using DM frorm the commend mode (or a special window, 
to be discussed later) allaws more lines tc fit on the screen, 
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Opernte on Memory 


Examine and Alter Hex Memory Dump 


UniLeb's hex/ASCII editor perrnits you to exernine and alter blacks of memory, 
and to rapidly page through consecutive blocks, 


From the main menu, press F3 for the sub-menu of memory operations, 


Press Fl and, when prompted for it, the starting address 0. 
The commend 0 MODIFY is executed, bringing a display of the first 90 
kytes of memory, The hex display is shown alongside the ASCII clisplay, 
The bottom line shows which keys control the editor. 


The first 18 hytes show the opcodes and velues of the initialization 
routine you disassembled previously, ending with the jump to 0082, 


Use the left-arrow end right-arrow keys to move the cursor, 
The cursor moves from address to address, sutormatically wrapping 
| around line endings. | 


Use the down-sarrow key to move denwn the rows. 
Ifyou scroll past the last line, the contents of additional addresses will 
be shown. 


Now use the up-arrow to move shove the line containing address C, 
A message states that you have entered target RAM, then the new 
address range is displayed. Ifyou access target RAM without first 
establishing debug control, UniLsb issues a non-maskshle interrupt ta 
get control of the necessary resources, 


PgDn and PgUp display consecutive blocks of memary, 
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Program instructions can be changed with the memory editor, kat you will use 
it raore often to modify data, to try a new value when initializing a register or 
varishle, or to edit text strings. 


Use Ctrl-Right Arrow to move the cursor into the ASCII display, 
Enter any ASCII charscters here, and their hex equivalents are shown 
to the left. Ctrl-Left Arrow micves the cursor back to the hex displey. 


Press Esc to leave the editor without saving this input. 
(figure 6-3] : 
Re-enter the eclitor hy pressing F1 and responding with address 0. 


Move the cursor to A2, where the delay loop's length is stored. 


Type 10 to replace the 40.. 
This alters the value that is decremented in this routine, effectively 
meking the delay loop shorter. 


Press End to save the change in program memory. 
UniLsb responds with "Changes saved." The LEDs blink much faster 
than before. If you wish, try other values at OOA2. 


Changes to memory remesin in effect until you change them again, or reloacl 
and restart the program. When you want a printed record of your changes to 
memory, the mode penel discussed later provides an option that will echo the 
CRT display to the printer, | | 
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LINE-BY-LINE ASSEMBLER 


Alter the Target Code 

Invoke the assembler at an address 
Use assembly language 

Overwrite program memory 


Write a Patch Routine 
Assign a patch address 
Write the new cade 
Jurnp te the patch 


Line-by-Line Assembler 


You can edit code and write small test routines or patches quickly with 
UniLab's assembler, bypassing the compile-sssemble-link process. You can alsa 
use it ta he certain a value appears on the bus, The assembler supports all 280 
instructions (except the * location counter), arithmetic expressions, and 
symbols. 


Alter the Target Code 

The sample program begins ky moving a block of memory from 0100 to 1800, 
but that code is never executed unless you alter the instruction at address 
OO8E so that it jumps to 1800 instead of 0088. This would he easy to change 
with the memory editor, but here we will use the line-hy-line asserabler, 

The sssembler is only available in cornmand mode. Start hy loacling the 
DEMO3,.TSK program (0 FFF BINLOAD DEMO3,TSK). 


Type 8E ASM to invoke the assembler, starting at address OO9E. 
The program cispleys the requested address OOSE, with the cursor 
indicating where the new assembly language instruction may be 
entered, 


Type JP 1800 <Enter>., 
This will assemble into jump to address 1800. The assembler now 
Offers the next acldlress for any further changes, 
[figure 7-3a] 
Press Enter to leave the contents of address 0091 unchanged and exit the 
assembler, Use STARTUP to execute the altered program. 
The LED sequence changes in accord with the new output routine. 


The analyzer can provide a filtered trace showing the new program flow. To do 
so, turn off reset with RESET’ (to skip the initislization sequence) snd type 
ONLY NOT AQ TO A9 ADR 3. You will see that the routine at 1800: 

-outputs | from A to the target port, 

- rotates the bit pattern in A (making the 1 an 8Q), 

- calls the delsy loop at AQ, 

- then jumps to 0088 to output the 80, 

-and ends up back at 1800 again, 
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Write a Patch Routine 

The assembler overwrites whatever is in memory. Extra instructions cannot be 
inserted between existing eddresses, but you can put in a jurnp to any unused 
area of mernory and write a multi-line patch there. 


For example, you can write code ta brings a register's contents onta the bus, 
Then that value, which would not appear on the bus otherwise, can be used to 
trigger a trace, 


Type 88 ASM to write new code beginning at address C088, 
At the 0088, type CALL 300 <Enter> 
At the OO&B, press <Enter> 


Now type 300 ASM <Enter> 
At the 0300, type GUT (79)A <Enter> 
0202 RRCA <Enter> 
0303 PUSH AF <Enter> 
0304 POP AF <Enter> 
0305 RET <Enter> 
O306 <Enter> 
(figure 7-3b] 
The UniLeb assembler provides the address numbers. A carriage return 
on & empty line preserves the previcus contents of that address, 


The above patch puts the contents of AF onto the bus before the delay loop is 
called end before A is sent to the target port. To trigger a breakpoint when the 
value 20 is in A: 


Type RI 20 DATA AFTER 303 ADR ADR SI. 
The breakpoint display shows 2060 in AF, end the microtarget's seconcl 


LED is lit, 


Type LP to execute the loop once, and you will see that the 20 in A causes the 
third LED to light, and that the RRCA instruction chenged A's value to 10, 
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Use Symbolic Labels 


Define syrnbols within UniLab 

Load a syrobol file 

List current symbols 

Use symbolic triggers end breakpoints 


Use Symbolic Labels 
UniLeh allows you to load aymbel tables generated by your linker, It supports a 
wide variety of symbol table formats, After loading a symbcl teble, the analyzer 
will display the same lebels as the source code. Or, if you wish, you can define 
symbols from within the UniLsb program, Triggers and breakpoints are easier 
to set, and a trece display is more quickly understood, with symbolic names, 


Load the DEMO3.TSK program and use STARTUP ta generate a trace display, 


Define Symbols Within UniLab 

Type 3 IS INIT_IX end 1234 IS VALUE_IX, 

[figure 7-4] 

Regenerate the trace display ky pressing Home. 
A new colurnn is added to the display, where the syrakolic name 
INIT_IX is shown beside address 0003, While the opcode for that 
address contains the value 1234, the mnemonics colurnn shows 
VALUE_IX, 


Load a Symbol File | 
You will usually load a target program's original symbol table, rather than 
assigning many new symbols individually: 


Type SYMFILE and, at the prornpt for a filename, type DEMO3.SYM. 
This calls up the Symbol File Format menu — choose F5, To see a list of 
the symbols that are now resident, type SYMLIST. 


Press Home to see the top of the trace clisplay again, 
[figure 7-5] 
Type NORMT OUT_LOOP ADR 5 to trigger the analyzer on the output loop. 


When symbolic lsbels have been defined, you can use thern with UniLsb - 
commands anywhere you would type in a value to examine rnemery (as in 
DELAY_LOOP MODIFY), or to set triggers and breakpoints, For added 
convenience during development work, refer to the related cornmends 
SYMSAVE, SYMFILE+, and SYMLOAD in the on-line glossary (type HELP 
<commend >), 
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CONTROL THE UNILAB ENVIRONMENT 


Control the displays 
Increase productivity 


Open Windows on Your Work 
Use general-purpose windows 
Generate a disassembly windy 
Change window sizes 


Use Function Keys 
Display function key assignments 
Reassign function keys 


Define Macro Commands 
Enable macro finctions 

Define a macro 

Assign rnacros to function keys 
Disable macro functions 


Use the Mode Panel 
Acijust the analyzer, displey, and log modes 


save Your Changes to the System 
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Control the UniLab Environment 
The features presented here affect the way UniLab : clisplsys information and 
responds to input. You can moclify the system's defsult settings to suit your 
particular neecls ancl work style. 


Open Windows on Your Work 

The display screen cen be divided into "windows." You can refer ta a 
disassernbly and a trace display at the same time, or keep a portion of one 
trace on the screen and generate a new one, You must lesve menu made in 
order to use screen windows, but call up the menus again any time you wish, 


Load the DEMO3.TSE program and enter RESET 88 AS to trigger the 
analyzer at acldress 0089, 
The screen fills with a trace display, 


Press F2 once to split the screen horizontally, 
4 line shows the screen division, and the lower half is cleared. The 
upper window retains its contents. Press End to move the cursor 
between windows. 


In coramend mode, F2 tagdles the eae t-screen display on and off, The 
same anelyzer settings, triggers, and debug options are in effect, 
regardless of which window you ue, 


Press PgDn to scroll through the trace buffer. 
One half of the screen rersins unchanged, while the window with the 
cursor responds to your keystrokes, 


In either windcaw, type RESET 88 RB. 
The active window shows the breakpoint display, while the other - 
window remains unchanged, 


Press F2 restore the full screen. 


These "general purpose" windows are easily used with most cornrnands, A 
special-purpose disassembly window will remain on the screen while you 
perform other functions. 
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Type 0 DN to disassemble memory, starting from address OOOU, 
A vertical rule delineates the right one-third of the screen, which 
displays the requested listing. Enough memory is disassembled to fill 
the windeny, 


Press F2 to split the screen, and type AQ DN to see more disassembled 
memory. 
The new disassembly is restricted to the height of the current window. 
{figure 8-2] 
The contents of the disassembly window remain in place, until you use: 
-anev DN command, 
- F2 to toggle the split-screen display, 
- End to move the cursor between windows, or 
-F10 to call up the main rnenu. 


You cen use up to four windows to visually compare: 
Target execution 
Disassernbled code 
Register displays 
Memory contents 
Help and other text files 


Help files will not be shown in their full width if there is an active disassembly 
window. Use F2 or End to adjust the displey appropriately. 


Change the Window Sizes 

Window dimensions can be modified. Perhaps you would like a nerrower 
dissssembly windcn, or a window that is only three or four lines high for 
breakpoint displays, 


Press Shift-F8 or type WSIZE. 
The screen temporerily clears, and the current window borders are 
displayed. Now use the arrow keys to adjust the dimensions of the 
windows, 


When you are satisfied, press End to accept the changes. 
The cispley is returned to its former state. Any new commends enterec 


will reflect the new window sizes, 
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Use Function Keys 

UniLsh uses function keys for eesy access ta often-used commends, which can 
save a great many keystrokes. Function keys can be used elone, or with the 
shift, Alt, or Ctrl keys. Not all have been pre-sssigned, and ell the keys are 
reessigneble. 


To see what functions ere assigned to the keys, use Fl, SHIFT-F1, ALT-F1, 
and CTRL-F1. It is easy to change or add finction-key sssignments, and any 
such changes will be shown in the displays. 


(figure 8-5] 


Reassign Function Keys 
Type 6 FREY PINOUT to assign the PINGUT commend to FS. 
Now, pressing F6 will display the pinout of your processar, 
[figure 3-6] 
You cen sssign a cornmend to any function key by using the words FKEY, 
SHIFT-FREY, ALT-FKEY, or CTRL-FKEY, Their syntex is the sare: 


ckhey#> FREY <commend> 


It is possible to assign strings of corarmends to a single fiction key, saving 
even more keystrokes. To do so, you must first learn to define a "macro" 
function that executes other commands. Then that macra's name can be 
assigned to a function key, (See entries in the on-line glossary for : and 
MACRO.) 
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Define Macro Commands 

Ifyou type the same ingmt often, consider defining it as a macro, When you 
enter 4 poe trigger spec repeatedly, for ipa making it a one-vord 
macro will save keystrokes and minimize typing errors, Macros can use UniLsk 
commends, data, and even commends from the undaniing proagrarnming 
language. Fach macro should have a unique name of any length (no spaces are 
allowed), 


To invoke these capebilities, type MACRO and a a carriage return. 
After a few seconds of clisk access ta meke macro fanctions and the 
programming language availeble, the gystern tells you that changes to 
the system can be mecde permanent with the SAVE-SYS command (S68 
below), 


Now, suppose you use a particular trigger specification often, In DEMO3TSE, 
for example, it was quite useful to filter the delay loop from the trace: 


Type : TRIGGER] NORMT ONLY NOT AO TO AQ ADR : <Enter> 

Now type TRIGGER 1 to enter the trigger spec, and S to start the analyzer. 
The trace is displayed in accordance with the trigger specifications, but 
without requiring all the parameters to he retyped each time the 


enalyzer settings have been changed. 


[figure 8-@] 


ZOO Tutorial — Page 44 


Contral the Unilab Environment 


Use the Mode Panel 

A three-part "mode panel" provides control of UniLeb's default settings, You 
can sirnplify the anelyzer display, log a session to disk or printer, anc disable 
the hardware interrupt, among other options. 


Press F8 to see the first page of the mode panel, 
The panel appears in the upper-right corner of the screen, This is the 
first of three pages that correspond to analyzer, display, and log moles, 
The down - and up-arrows move the cursor from item to itern. 

[figure 8-9] 

Ifyou da nat pees the dizasszembly, control, or miscellaneous inputs, that data 

can be removed easily fram the display: 


On the mode panel's first page, with the cursor beside "DISASSEMBLER," 
press the right-arrow to turn off the disaszembler. 
The disassembler abhvays tries to interpret trace date az if it were from 
consecutive cycles, In a nerrowly filtered trace, that can be 
inappropriate. At such times, turn off the cisassermbler to avoid 
contusing, incorrect mnemonics, 


Press PgDn to move to the panel's next page, then use the arrow keys to 
turn off the MISC and CONT columns. 


Press End when you are done, and use STARTUP to start the analyzer; the 
trace reflects the changes you mace by suppressing the CONT, MISC, and 
mnemonics colurmns, 


You can press F8 to return to the mode panel and restore the default settings, 


—_ 


save Your Changes to the System 

Whenever you alter the deftult UniLeb environment and wish to make the 
change permanent, type SAVE-3YS before exiting the prograra and provide 
the filename you will use to load the program (e.g., ULZS0MOD}. The new 
settings will be in effect the next time you use UniLsh, Users of floppy-hasec 
systems will have to seve the new filename to drive B or save their settings in 
the arene ULZe0 file. 
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